---
title: Slider
description: An input where the user selects a value from within a given range.
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/Slider.html
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/inputs/slider.mdx?plain=1
---

<ComponentPreview
  name="slider/demos/default"
  preview={`<Slider defaultValue={50} />`}
/>

## Installation

```package-install
npx shadcn@latest add @dotui/slider
```

## Usage

Use slider to allow users to select a value from within a given range.

```tsx
import { Slider } from "@/components/core/slider";

<Slider
  defaultValue={50}
  label="Opacity"
  description="Adjust the background opacity."
/>;
```

```tsx
import { Description, Label } from "@/components/core/field";
import {
  SliderFiller,
  SliderRoot,
  SliderThumb,
  SliderTrack,
  SliderValueLabel,
} from "@/components/core/switch";

<SliderRoot defaultValue={50}>
  <Label>Opacity</Label>
  <ValueLabel />
  <SliderTrack>
    <SliderFiller />
    <SliderThumb />
  </SliderTrack>
  <Description>Adjust the background opacity.</Description>
</SliderRoot>;
```

## Options

### Size

Use the `size` prop to control the size of the slider. The default variant is `"md"`.

<ComponentPreview
  name="slider/demos/sizes"
  preview={`<Slider size="sm" />
<Slider size="md" />
<Slider size="lg" />`}
/>

### Orientation

Sliders are horizontally oriented by default. The `orientation` prop can be set to `"vertical"` to create a vertical slider.

<ComponentPreview
  name="slider/demos/vertical"
  preview={`<Slider orientation="vertical" />`}
/>

### Label

A visual label can be provided using the `label` prop or a hidden label using `aria-label` prop.

<ComponentPreview
  name="slider/demos/label"
  preview={`<Slider label="Opacity" defaultValue={50} />
<Slider aria-label="Opacity" defaultValue={50} />`}
/>

### Description

A description can be supplied to the slider using the `description` prop.

<ComponentPreview
  name="slider/demos/description"
  preview={`<Slider label="Opacity" description="Adjust the background opacity." />`}
/>

### Value label

The `valueLabel` boolean prop can be used to display the current value of the slider. The `valueLabel` prop can also be set to a function that returns a custom value label.

<ComponentPreview
  name="slider/demos/value-label"
  preview={`<Slider label="Donuts to buy" valueLabel />
  <Slider
    label="Donuts to buy"
    valueLabel={(donuts) => \`\${donuts[0]} of 100 Donuts\`}
  />`}
/>

### Value scale

By default, slider values are precentages between 0 and 100. A different scale can be used by setting the `minValue` and `maxValue` props.

<ComponentPreview
  name="slider/demos/value-scale"
  preview={`<Slider label="Cookies to buy" minValue={1} maxValue={50} />`}
/>

### Step

The `step` prop can be used to snap the value to certain increments.

<ComponentPreview
  name="slider/demos/step"
  preview={`<Slider label="Opacity" step={5} />`}
/>

### Format options

Values are formatted as a percentage by default, but this can be modified by using the `formatOptions` prop to specify a different format.
`formatOptions` is compatible with the option parameter of [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) and is applied based on the current locale.

<ComponentPreview
  name="slider/demos/format-options"
  preview={`<Slider label="Price" formatOptions={{ style: "currency", currency: "JPY" }} />`}
/>

### Range

Passing an array to the `defaultValue` or `value` props will create a range slider.

<ComponentPreview
  name="slider/demos/range"
  preview={`<Slider defaultValue={[200, 300]} />`}
/>

### Disabled

Use the `isDisabled` prop to disable the slider.

<ComponentPreview
  name="slider/demos/disabled"
  preview={`<Slider isDisabled />`}
/>

## Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview
  name="slider/demos/composition"
  preview={`<SliderRoot>
    <Label>Volume</Label>
    <SliderValueLabel />
    <div>
      <Volume1Icon />
      <SliderTrack>
        <SliderFiller />
        <SliderThumb />
      </SliderTrack>
      <Volume2Icon />
    </div>
  </SliderRoot>`}
/>

## Uncontrolled

The `defaultValue` prop can be used to set the default state.

<ComponentPreview
  name="slider/demos/uncontrolled"
  preview={`<Slider defaultValue={20} />`}
/>

## Controlled

Use the `value` and `onChange` props to control the value of the input.

<ComponentPreview
  name="slider/demos/controlled"
  preview={`const [value, setValue] = React.useState(50);
return <Slider value={value} onChange={(value) => setValue(value as number)} />;`}
/>

## API Reference

| Prop            | Type                                                                                                | Default        | Description                                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `size`          | `"sm" \| "md" \| "lg"`                                                                              | `"md"`         | The size of the slider.                                                                                      |
| `valueLabel`    | `boolean \| ((value: number[]) => string)`                                                          | `false`        | Weather to display the value label. A function may be provided to customize the value label.                 |
| `label`         | `ReactNode`                                                                                         |                | The content to display as the label.                                                                         |
| `description`   | `ReactNode`                                                                                         |                | A description for the field. Provides a hint such as specific requirements for what to choose.               |
| `formatOptions` | `Intl.NumberFormatOptions`                                                                          | -              | The display format of the value label.                                                                       |
| `orientation`   | `'horizontal' \| 'vertical'`                                                                        | `'horizontal'` | The orientation of the Slider.                                                                               |
| `isDisabled`    | `boolean`                                                                                           | -              | Whether the whole Slider is disabled.                                                                        |
| `minValue`      | `number`                                                                                            | `0`            | The slider's minimum value.                                                                                  |
| `maxValue`      | `number`                                                                                            | `100`          | The slider's maximum value.                                                                                  |
| `step`          | `number`                                                                                            | `1`            | The slider's step value.                                                                                     |
| `value`         | `T`                                                                                                 | -              | The current value (controlled).                                                                              |
| `defaultValue`  | `T`                                                                                                 | -              | The default value (uncontrolled).                                                                            |
| `name`          | `string`                                                                                            | -              | The name of the input element, used when submitting an HTML form.                                            |
| `children`      | `ReactNode \| (values: SliderRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | -              | The children of the component. A function may be provided to alter the children based on component state.    |
| `className`     | `string \| (values: SliderRenderProps & {defaultClassName: string \| undefined}) => string`         | -              | The CSS className for the element. A function may be provided to compute the class based on component state. |
| `style`         | `CSSProperties \| (values: SliderRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -              | The inline style for the element. A function may be provided to compute the style based on component state.  |

| Event         | Type                 | Description                                              |
| ------------- | -------------------- | -------------------------------------------------------- |
| `onChange`    | `(value: T) => void` | Handler that is called when the value changes.           |
| `onChangeEnd` | `(value: T) => void` | Fired when the slider stops moving, due to being let go. |

| Data attribute                                | Description                     |
| --------------------------------------------- | ------------------------------- |
| `[data-orientation="horizontal \| vertical"]` | The orientation of the slider.  |
| `[data-disabled]`                             | Whether the slider is disabled. |

## Accessibility

### Keyboard interactions

| Key                                            | Description                                                                                                                             |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `Tab`                                          | Places focus on the handle. If the handle is already in focus, moves focus to the next handle or next element in the page tab sequence. |
| `Shift+Tab`                                    | Places focus on the previous handle or previous element in the page tab sequence.                                                       |
| `ArrowUp` `ArrowDown` `ArrowLeft` `ArrowRight` | Moves the handle up/down/left/right.                                                                                                    |
